Custom Fields

Custom fields are business-specific fields that you can define for a work item. You can use work item rules to control what custom fields display on work items at various nodes. For example, a custom field might be required for a work item at one node and might be protected or absent on the same work item at another node.

To see how operators interact with work item fields, see the XTRAC Workbench User Guide.

In XTRAC Workbench, when an operator clicks the hyperlink field, XTRAC adds extra information to the actual URL, which results in a URL that can be opened in a browser. XTRAC populates any data inserts in the URL with data from the actual XTRAC fields. Literal values can also be used for fields. For example, the parameter field.

The information that is added is based on the following rules:

• If the field is a non-XTRAC field, it is appended to the URL as: Parameter=Field.
• If the field is a custom field that is present on the work item and its value is null, it is appended to the URL as Parameter=Field.
• If the field is a custom field that is present on the work item and it has a value, it is appended to the URL as Parameter=xxxx.
• If the field is any of the following fields and the value from the work item is null, it is appended to the URL as Parameter=. If the field has a value in the work item, it is appended to the URL as Parameter=xxxx.
  
  • Cause
  • SubCause
  • Communication Type
  • Phone Number
  • Phone Extension
  • Middle Name
  • Account Number
  • Amount (Default value is zero or Parameter=0)

Custom fields can be shared, monitored, sensitive (not shared with services outside of XTRAC), hyperlinks, multi-lined, multi-select, and inactive. See Shared Custom Fields, Monitored Custom Fields, Sensitive Custom Fields, Multi-Select Custom Fields, and Inactive Custom Fields.

When you associate a custom field with a work item rule, you can indicate the subtypes it displays with. You can specify the following information:

Note: A custom field that displays in a work item rule with all subtypes cannot also display with a specific subtype. The reverse is also true.

XTRAC can process up to 500 active custom fields at a time. There is no limit to the number of inactive custom fields you can have.

Before you can create a custom field, you must create the following components:

• External service
  • Note: You cannot configure a multi-select field for external use.
• Exception policy

Also, before you can create a custom field that has a hyperlink data type, you must create a URL.

Shared Custom Fields

The data in custom fields that are shared between split linked items can be shared by all of the work items that belong to the same split family. If the value in this field changes, XTRAC updates the value on all of the work items in the split family.

If the field is not a shared field and the value changes on one work item in the split family, the value is not updated in the other work items that belong to the split family.

Shared fields might become locked. The first operator that opens a work item that belongs to a split family locks all of the shared fields in all of the work items for the family. If another operator opens a work item that belongs to the same split family before the first operator finishes processing and closes the work item, XTRAC displays the shared fields as disabled and does not let the second operator make any changes.

See Unlock Work Items.

Note: After you specify that a field is a shared field, you cannot remove that attribute. Also, shared fields cannot be marked as external fields.

Monitored Custom Fields

If you create a custom field as a monitored field, XTRAC’s business activity monitoring tool monitors the field.

Note: Multi-line and multi-select fields cannot be monitored.

The following rules apply to monitored fields:

• Monitored fields cannot be marked as sensitive or external fields.
• Monitored fields cannot be defined as a hyperlink data type.

Sensitive Custom Fields

You can specify that values of a custom field are sensitive. Do not send these values to systems that are outside of XTRAC. For example, if an external monitoring tool sends feeds from XTRAC, the data in sensitive custom fields is not sent.

The following rules apply to sensitive fields:

• Sensitive fields cannot be monitored or marked as external.
• Sensitive fields cannot be defined as a hyperlink data type or used when you define an action for a hyperlink data type field. However, they can be used in the condition.

Metadata Custom Fields

Metadata custom fields are defined in XTRAC or in systems outside of XTRAC. For example, Documentum. There is no direct tie between XTRAC and any outside system where metadata fields were defined

Only custom fields can be set as metadata fields. Metadata fields do not apply to predefined fields.

The Metadata Field Summary window contains a column that indicates with a check mark those fields that are metadata custom fields. The check mark can be toggled on and off.

Only metadata custom fields are listed in the Action Tab for metadata rules.

Multi-Select Custom Fields

Multi-select custom fields let an XTRAC user select several values for the same field.

If you have the Create security function, when you create a custom field you can define that field as a multi-select field by setting its data type to Multi-Select. See Creating a Custom Field.

After you create a multi-select field, that field is saved to the database when you save it.

You can also open and copy existing multi-select custom fields. If you have the necessary security functions, you can open a multi-select custom field and mark it for deletion. If you need to stop a multi-select field from being deleted and the nightly batch file has not run yet, you can click the check mark in the delete column and save the multi-select field from being deleted. See Deleting a Custom Field.

You can perform the following actions when you create a multi-select custom field:

• Name it (subject to existing naming restrictions).
• Label it to define how it is labeled in work items.
• List numerous valid values for it. (However, large amounts of values might affect performance.)
• Groups values into subsets (value groups).
• Share it with all work items in a family. See Multi-Select Fields and Split Rules.
• Mark it as sensitive. See Sensitive Custom Fields.
• Associate it with a change request ID.
• Provide a reason for creating it.
• Check any dependencies on it. See Dependencies.
• Place the field where you want it to display on a work item. See Positioning the Fields On a User-Defined Work Item. The position you choose is similar to where the MSF displays in XTRAC Workbench in a production environment.

You cannot configure a multi-select field for external use.

Note: The NoCheck data mask is the only data mask that is available for a multi-select custom field.

If you create a standard work item rule, you cannot select a multi-select field. See Creating a Standard Work Item Rule. When you select the standard item class, XTRAC filters out all multi-select custom fields from the add a field drop-down list. If you want to select a multi-select field for a work item rule, create a user-defined work item rule. See Creating a User-Defined Work Item Rule.

You can populate rule list groups from a multi-select field. See Examples of Multi-Select Conditions and Rule List Groups.

You cannot configure a multi-select field for monitoring.

You can determine the layout of MSF in work item rules for organization and efficient use. See Positioning the Fields On a User-Defined Work Item. The MSF position in the layout window is similar to its position in XTRAC Workbench in a production environment.

If you include a multi-select custom field (MSF) in a work item rule, you can update that field using a work item update rule. The update can be based on other fields in the work item. The MSF can be set to only a single value, which must be selected from the valid values for the MSF. The new value replaces and does not add to the original value in the target field. See Work Item Update Rules.

Note: MSFs are not supported for Common Field Groups. See Common Field Groups.

Custom Fields with External Data

With the exception of multi-select custom fields, XTRAC lets you define a custom field as an external field. The data that populates an external field comes from a system outside of XTRAC. You must also specify the external service to use for retrieving the data and the exception policy to use when a retrieval fails. You can also specify what service to use for updating a field that contains external data.

The following rules apply to external fields:

• External fields cannot be monitored.
• External fields cannot be marked as sensitive or shared.
• External fields cannot be defined as a hyperlink data type.

External fields and their values are listed in the XTRAC UI. However, they are not stored in the database. When you retrieve a work item that has external fields, XTRAC sends a request to the external service to retrieve the latest values for the external fields. When you save a work item that has external fields, the values for the external fields are filtered out and any updated values are sent to the external service. Therefore, when XTRAC Event Notification (XEN) events occur, the values for external fields are not available to XTRAC.

Note: All external fields in a work item are automatically copied when you copy that work item, whether those external fields are protected or unprotected fields. When you save the copied work item, any values for protected external fields are also sent to the specified external service. Because these values are protected, you cannot change them or delete them before they are sent to the external service. If you intend for a specific work item to be copied, we recommend that you do not include protected external fields in that work item.

Custom Fields and Hyperlinks

XTRAC supports a hyperlink data type. With this data type, you can create a field that looks like a hyperlink in XTRAC Workbench. An operator can then click the link and have it open a new window.

You can specify hyperlink fields as part of a work item rule or as a column in a work list in work list rules. In XTRAC Workbench, an operator can search for a work item using a hyperlink field.

The hyperlink data type is comprised of a URL and conditions associated with its use. You must define the URL component separately.

Note: Hyperlink fields cannot be marked as sensitive, external, or monitored.

In XTRAC Workbench, when an operator clicks the hyperlink field, XTRAC adds extra information to the actual URL, which results in a URL that can be opened in a browser. XTRAC populates any data inserts in the URL with data from the actual XTRAC fields. Literal values can also be used for fields. For example, the parameter field.

The information that is added is based on the following rules:

• If the field is a non-XTRAC field, it is appended to the URL as: Parameter=Field.
• If the field is a custom field that is present on the work item and its value is null, it is appended to the URL as Parameter=Field.
• If the field is a custom field that is present on the work item and it has a value, it is appended to the URL as Parameter=xxxx.
• If the field is any of the following fields and the value from the work item is null, it is appended to the URL as Parameter=. If the field has a value in the work item, it is appended to the URL as Parameter=xxxx.
  • Cause
  • SubCause
  • Communication Type
  • Phone Number
  • Phone Extension
  • Middle Name
  • Account Number
  • Amount (default value is zero or Parameter=0)
    

Inactive Custom Fields

When a work item uses a custom field that has a value, that value stays with the work item. A work item can then arrive at a node where the work item rule does not use a custom field. That custom field is inactive at that node.

The following guidelines apply to inactive custom fields:

• On standard work items that are defined by XTRAC, the custom field displays but operators cannot change it.
• On user-defined work items, the custom field does not display.

Custom Field Data Types

Most custom field data types support display masks that control how data displays to an operator. For example, you can define a Boolean display mask that causes the options to appear as Yes/No, On/Off, or True/False.

For some display masks, you also can specify the default field length or the maximum number of characters that an operator can enter for the custom field value.

The following table specifies the display mask that is available for each data type, including a description of each display mask and the default length and any maximum length of the display mask:

Value Group Data Type

The Value Group data type contains a defined list of values. For example, you can define a Days of the Week custom field that has a Value Group data type. You can then define the valid values as Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday.

You can also subdivide the valid values into value groups. Value groups limit the values that are available to the operator in a particular work item rule. For example, you define two value groups for the custom field called Days Of The Week. The Weekend value group includes Saturday and Sunday. The Week Days group includes the Monday through Friday values. When an operator is processing a work item that contains the Days Of The Week custom field, you can specify the Weekend value group as the default. The operator then has only Saturday and Sunday to choose from when populating the Days Of The Week field.

Creating a Custom Field

Note: To define a custom field, you need the Create and User-Defined Field security functions as part of the security group that is associated with your entitlement set.

IMPORTANT: You cannot make changes to the name or to the Shared Between Split Linked Items check box after you save a custom field.

To create a custom field

1. In Feature Explorer, click Fields > Custom Fields.
2. In the Custom Fields Summary window, click New.
3. In the Custom Field Detail window, on the General tab, type the name, description, data type, display mask, and length.

Note: You cannot create a custom field with CustomerName as the name of the field or any variations with spaces. For example, do not use any of the following names:

• CustomerName
• Customer Name
• Customer  Name
• C u s t omerN ame
• C u s t o m e r N a m e

Note: You cannot make changes to the name or data type after you save a custom field.

Note: The description of the field that appears as the field label in XTRAC Workbench.

See Custom Field Data Types.

Note: You can create a multi-select field by selecting Multi-Select in the Data Type drop-down list. After you save a field with a multi-select data type, you cannot change its data type to any other data type.

4. (Optional) Depending on the data type of the field, check the check boxes for the Shared, Sensitive, Monitored, or External Field options.

If you select Shared, you cannot change the attribute. XTRAC disables the check box.

If you select External Field, you must type a value in the External Service for Receive and Exception Policy fields.

5. In the Help Text field, type any text that you want to display for the Help.
6. (Optional) In the Change Request ID field, type the ID of the change request (up to 30 characters).
7. (Optional) In the Memo field, type the reason for creating the custom field (up to 60 characters).
8. Click Save.

XTRAC saves the custom field. You can now add the values that are allowed for your custom field and group those values. See Adding Values to a Custom Field and Creating a Value Group.

Adding Values to a Custom Field

If you create a custom field with a Value Group data type, you can add a list of valid values to this field. When this field displays on a work item, an operator can select one of the values that you define.

You can also add values to a multi-select custom field using this process. See Multi-Select Custom Fields.

Note: If you change the data type of a custom field to any other data type, XTRAC removes the values that are associated with the value group. If you change the data type back to a value group, XTRAC adds the valid values back into the custom field details after you save the data type change.

To add values to a custom field that has a data type of Value Group

1. Create a custom field of the Value Group data type by following the steps at Creating a Custom Field.
2. Click the Valid Values tab.
3. In the grid at the bottom, in the Click here to add a new valid value row, type a name (up to 60 characters) and a description (up to 60 characters) for the field value.
4. (Optional) In the Change Request ID field, type the ID of the change request (up to 30 characters).
5. (Optional) In the Memo field, type the reason for creating or updating the rule (up to 60 characters).
6. Click Save.

XTRAC adds the new value to the list.

Note: To remove a value from the list, select the value, and then click Delete. You can also check the Delete check box directly.

7. For every value that you want to add, repeat Steps 3-6.

Creating a Value Group

After you create a list of values for a custom field with a Value Group data type, you can group the values so that operators have a smaller list of values to choose from when processing a work item.

This process also works for multi-select custom fields. See Multi-Select Custom Fields.

To create a value group

1. In Feature Explorer, click Fields > Custom Fields.
2. In the Custom Field Summary window, click the custom field you want to create a value group for.
3. In the Custom Field Detail window, click the Valid Values tab.
4. In the Valid Values tab, at the right side, click Value Group.
5. In the Value Group Summary window, click New.
6. In the Value Group Detail window, at the right side, click Add.

7. In the Select Valid Values window, select the valid values you want to add, and then click OK.

   XTRAC closes the window and the values display on the Value Group Detail window.

8. (Optional) In the Change Request ID field, type the ID of the change request (up to 30 characters).
9. (Optional) In the Memo field, type the reason for creating or updating the rule (up to 60 characters).
10. Click Save.

XTRAC saves the new value group. The next time you open the Value Group Summary window for this custom field, the new value group displays in the list.

Creating a Hyperlink Custom Field

You can add a hyperlink field to a work item rule. Then, when an operator creates a work item of a specific item type, one of the fields on the work item is a hyperlink. When the operator clicks this field, a browser window opens. You specify the browser window to open based on the selected URL and any additional parameters that you enter.

Before you create a hyperlink field, you must create the URL to associate with this field.

Note: To define a hyperlink custom field, you need the Create and User-Defined Field security functions as part of the security group that is associated with your entitlement set.

To create a hyperlink custom field

1. In Feature Explorer, click Fields > Custom Fields.
2. In the Custom Field Summary window, click New.
3. In the Custom Field Detail window, in the General tab, type a name and a description for the hyperlink field.
4. From the Data Type drop-down list box, select Hyperlink.

XTRAC fills in the No Check display mask and a length of 60.

See Custom Field Data Types.

5. In the Display Label check box, enter the label that you want XTRAC Workbench to display for this hyperlink field.
6. Click Save.

IMPORTANT: You must save the field before you can add a hyperlink rule.

7. Click New.
8. In the Hyperlink Rule Detail window, build the rule conditions by selecting the fields, criteria, and values.

See Rule Conditions and Building a Rule Condition.

9. Click the Action tab.
10. In the Action tab, in the Window Name field, type a name for the window that XTRAC opens when the operator click the hyperlink in XTRAC Workbench.

This step prevents multiple windows from opening when a hyperlink is clicked multiple times.

11. In the URL field, select the URL to associate with this hyperlink.

The URL is a separate component that you must define before you can create a hyperlink custom field.

12. Type any additional text that is needed for the hyperlink beyond what information is contained in the URL, and then type the field.

NOTE: This screen has its own history that is independent of the field history.

See Additional Hyperlink Text.

13. (Optional) In the Change Request ID field, type the ID of the change request (up to 30 characters).
14. (Optional) In the Memo field, type the reason for creating the hyperlink (up to 60 characters).

Additional Hyperlink Text

You can add text for a hyperlink custom field. This text displays in addition to the URL that you specify. See Creating a Hyperlink Custom Field.

IMPORTANT: XTRAC uses the built-in Java URLEncoder class to encode the hyperlink parameters. This class uses the UTF-8 encoding scheme. Spaces and special characters from the hyperlink rule parameter fields are encoded in the URL when the hyperlink is launched in XWB.

For example, the space character is encoded as %20 or +. Both are acceptable formats. The space character is automatically encoded to + by the URLEncoder.

For example, the final hyperlink text (after the URL) is WOSID=1234&CCN=2233. The values 1234 and 2233 come from XTRAC fields. You would enter the following parameters and fields:

In XTRAC Workbench, when the operator clicks the hyperlink field, XTRAC adds the parameters to the actual URL which results in a URL that can be used in a browser. XTRAC populates the data inserts with data from the actual XTRAC fields.

IMPORTANT: XTRAC Workbench has a limit on the completed URL of 2,048 characters. Because the final URL combines the string from the XTRAC URL component and the parameters from the hyperlink and substitutes real data for the data inserts, XTRAC cannot validate the length of your URL. It is possible to create a parameter list that results in a string that exceeds this maximum length at runtime.

Because the hyperlink field can be quite long when it displays to the operator, ensure that you have created a wide enough field size when laying out the work item so that the link does not display with a scroll bar. The operator cannot launch the hyperlink if a scroll bar displays.

Copying a Custom Field

You can copy a custom field.

To copy a custom field

1. In Feature Explorer, click Fields > Custom Fields.
2. In the Custom Field Summary window, click the name of the field that you want to copy.
3. Click Copy.
4. In the Custom Field Detail window, in the General tab, type a unique name for the field.

You can now change any of the fields for your copied custom field, including its description, data type, display mask, length, external service information, exception policy, help text, valid values and value groups, change request ID, and memo.

5. When you are finished making changes to your copied custom field, click Save.

Opening a Custom Field

You can open a custom field that was previously created.

To open a custom field

1. In Feature Explorer, click Fields > Custom Fields.
2. In the Custom Field Summary window, click the name of the field that you want to open.
3. Click Open.
4. In the Custom Field Detail window, on the General and Valid Values tabs, you can view all of the information for the field.

You can also change some of the fields for your copied custom field, including its description, data type, display mask, length, external service information, exception policy, help text, valid values and value groups, change request ID, and memo.

5. If you made changes to the custom field, click Save. Or click Close and any changes you made are lost.

Deleting a Custom Field

You can mark a custom field for deletion during the nightly batch file cycle.

To delete a custom field

1. In Feature Explorer, click Fields > Custom Fields.
2. In the Custom Field Summary window, click the name of the field that you want to delete.
3. Click Open.
4. In the Custom Field Detail window, on the General tab, in the top right corner, click the check box next to the trash can symbol.
5. Click Save.

In the Custom Field Summary window, in the last column (marked for delete), a check mark displays next to the custom field that you want to delete. If all of the dependencies for the field are resolved, the field will be deleted during the nightly batch cycle.

Copyright © 2011-2014 XTRAC, LLC. All rights reserved.